home *** CD-ROM | disk | FTP | other *** search
/ Merciful 1 / Merciful - Disc 1.iso / software / d / devpak / devpakv3.01kickstartv1.3b.dms / devpakv3.01kickstartv1.3b.adf / arp / Programmers_Manual next >
Text File  |  1991-11-20  |  13KB  |  463 lines
  1.  
  2.  
  3.  
  4.            AmigaDOS Replacement    Project    V1.1 (REL2)
  5.  
  6.  
  7.                  AmigaDOS Replacement
  8.                  Project V1.1 (REL2)
  9.  
  10.  
  11.                    ABSTRACT
  12.  
  13.  
  14.  
  15.       An overview of the new functions and support materials
  16.       available to programmers using ARP, including    a discussion
  17.       of calling arp.library from the C language.
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.                  CONTENTS
  75.  
  76.        Current Status of ARP................................  1
  77.  
  78.        1.  Changes to old functions.............................  1
  79.        1.1    GADS()..........................................  1
  80.        1.2    FileRequest()...................................  1
  81.  
  82.        2.  New Functions........................................  2
  83.        2.1    Process    Control    and Resident....................  2
  84.        2.2    Date functions..................................  3
  85.        2.3    Misc functions..................................  3
  86.  
  87.        3.  Language Support.....................................  3
  88.        3.1    C Language Support..............................  4
  89.        3.2    Modula II support...............................  5
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.                   - i -
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.        ARP Prog    Manual       V1.1    Software (REL2)      February 22, 1988
  137.  
  138.  
  139.  
  140.        Current Status of ARP
  141.  
  142.        This release meets our first goal in producing ARP. It is
  143.        now possible for    users of the Amiga to work in a    practically
  144.        BCPL free environment, allowing programmers to write
  145.        software    free of    BCPL headaches.     This release of the
  146.        library (arp.library) introduces    what we    feel are important
  147.        advances    and standards for the Amiga, including new process
  148.        control functions and a resident    program    standard.  Old
  149.        functions have been enhanced, the GADS()    argument parser    now
  150.        supports    a new template type which allows the user to enter
  151.        any number of arguments,    and the    FileRequest() has been very
  152.        greatly enhanced, it now    sports a parent    gadget,    and
  153.        provides    much more programmer control than previously. It is
  154.        beautiful.
  155.  
  156.  
  157.        1.  Changes to old functions
  158.  
  159.        Only GADS() and FileRequest() received significant
  160.        enhancements.  Both of these are    completely compatible with
  161.        older code.
  162.  
  163.        1.1  GADS()
  164.  
  165.        The only    change to GADS() is the    introduction of    a new
  166.        template    type which allows any number of    arguments to be
  167.        placed on the command line.  It consists    of the usual slash
  168.        followed    by three periods (/...).  On return from GADS(),
  169.        the array element which corresponds to the multiarged type
  170.        will be a pointer to another array of character pointers    (
  171.        *(**char)) which    contain    the actual arguments entered by    the
  172.        user.  This array is guranteed to be null terminated.  See
  173.        the GADS    manual page for    more information.  Note    that the
  174.        ugly and    limited    ",,,," construct is still supported if you
  175.        are into    commas.
  176.  
  177.        1.2  FileRequest()
  178.  
  179.        FileRequest has been greatly enhanced and extended in this
  180.        release.     You can now alter FileRequest's window, add or
  181.        subtract    your own gadgets, handle gadget    events relating    to
  182.        your own    gadgets, and so    on.  The FileRequester structure
  183.        has been    changed, however old code using    the old
  184.        FileRequester structure will still work as long as you set
  185.        the old fr_Flags    variable to zero as warned.  See the
  186.        FileRequest() manual page and arpbase.[ih] for more
  187.        information.
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.                  Page 1
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.        ARP Prog    Manual       V1.1    Software (REL2)      February 22, 1988
  203.  
  204.  
  205.  
  206.        2.  New Functions
  207.  
  208.        Many new    functions have been added in this release. Perhaps
  209.        the most    important are the process control functions and    the
  210.        date functions.    The date functions support international
  211.        date formats for    both input and output, and were    provided by
  212.        Ken Salmon.
  213.  
  214.        2.1  Process Control and Resident
  215.  
  216.        arp.library now has a background    process    spawner    which
  217.        should eliminate    any future need    for programs to    call
  218.        Execute(). You can set many options with    this function
  219.        including stdio handles,    or you can specify a flag which
  220.        will create a new interactive environment for the process.
  221.        Note that this function creates new CLI style processes as
  222.        its default actions, and    it may be called from Workbench
  223.        programs.  It also searches the Resident    list first, and    so
  224.        may be used to run multiple copies of the same code, and    it
  225.        automatically takes advantage of    stack settings using the
  226.        new ResidentProgramTag.
  227.  
  228.         The    spawner    will not execute BCPL programs.    This would
  229.        have been done if it were reasonably possible to    do so, but
  230.        it was not.  However, now that most of the ARP command
  231.        replacements are    done this should not be    an issue, since    any
  232.        disk which has arp.library will also have the command
  233.        replacements. The spawner will return an    error code to you,
  234.        at which    point you can inform the user, or attempt to
  235.        execute the BCPL    program    using Execute(), and all its
  236.        attendent problems.
  237.  
  238.         The    spawner    causes processes to automatically clean    up
  239.        after themselves, this includes closing all stdio handles
  240.        and freeing stack and possibly also data    memory,    if that    was
  241.        allocated by the    startup    code, so there is no reason for
  242.        your program to hang around waiting for child exits,
  243.        although    you can    if you wish to.     For more information, see
  244.        the ASyncRun() manual page.
  245.  
  246.        2.1.1  Resident programs     This release introduces a method
  247.        for creating shared text    processes on the Amiga.     The code
  248.        for these processes in the past has had to be reentrant,    and
  249.        that is still the simplest case.     ARP provides a    method for
  250.        specifying that a separate data segment should be allocated
  251.        if your program is resident, and    you can    then copy the data
  252.        to the new data segment,    and use    that, thus preserving a
  253.        clean slate for the next    execution.  The    compiler startup
  254.        code is responsible for initializing the    data segment.  This
  255.        was done    to keep    the support routines as    general    as
  256.        possible, the actual data copying is extremely short, as    a
  257.  
  258.  
  259.  
  260.                  Page 2
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.        ARP Prog    Manual       V1.1    Software (REL2)      February 22, 1988
  269.  
  270.  
  271.  
  272.        look at the arprescrt0.s    source will demonstrate.
  273.  
  274.         Users now have a program to    install    processes as
  275.        Resident    as well    as a program to    execute    these processes.
  276.        Hopefully more people will take advantage of the    new
  277.        resident    standard and write more    of this    low overhead
  278.        software.  For more informtion, see the manual page for
  279.        Resident    in the users manual, and the AddResidentPrg() and
  280.        LoadPrg() etc., functions in the    programmers manual.
  281.  
  282.        2.2  Date functions
  283.  
  284.        These date functions provide a method for converting between
  285.        AmigaDOS    datestamps and strings and vice-versa.    These
  286.        functions provide a wide    variety    of international date
  287.        format input and    output conversions. You    must specify the
  288.        conversion you want.  The ARP standard has been to accept
  289.        the value of the    dateformat environment variable    as set by
  290.        users. If this is undefined, default to the current AmigaDOS
  291.        convention.  You    must check this    variable yourself, the
  292.        StrtoStamp() and    StamptoStr() functions will not    do this    for
  293.        you.  For more information see the manual pages for these
  294.        two functions, as well as the DateTime struct in
  295.        arpbase.[ih].
  296.  
  297.        2.3  Misc functions
  298.  
  299.        The following utility functions have been added in V33.4:
  300.  
  301.       - PreParse() - prepare a string for PatternMatch()
  302.  
  303.       - LMult(), LDiv(), LMod() - LONG multiply divide and
  304.         modulus routines.
  305.  
  306.       - TackON() - add a filename to a pathname.
  307.  
  308.       - BaseName() - return    a pointer to the BaseName of a
  309.         PathName.
  310.  
  311.  
  312.        3.  Language Support
  313.  
  314.        Support is provided in the form of header files and linkable
  315.        libraries or pragma files for Aztec C, Lattice C    TDI Modula
  316.        II, and of course assembler.
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.                  Page 3
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.        ARP Prog    Manual       V1.1    Software (REL2)      February 22, 1988
  335.  
  336.  
  337.  
  338.        3.1  C Language Support
  339.  
  340.        Startup code which automatically    opens arp.library and
  341.        initializes IntuitionBase and GfxBase as    well as    ArpBase    is
  342.        provided    for both Lattice and Manx.  We have attempted to
  343.        keep filename conventions and header file proliferations    to
  344.        a minimum, and have succeeded pretty well so far, so the
  345.        discussion which    follows    apply equally well to both
  346.        compilers.
  347.  
  348.         To use the automatic startup code, simply link with
  349.        arp.lib.    This will perform the automatic    library    opens
  350.        described above and also    automatically call the GADS()
  351.        argument    parser to parse    the command line if you    are running
  352.        from the    CLI.  A    default    template is used which basically
  353.        allows users to enter arguments.     If you    wish to    change this
  354.        template, simply    set a variable by the name of CLI_Template
  355.        to point    to the character string    you wish to use    for a
  356.        template.  You can also provide the optional extra help
  357.        message of your choice by providing a CLI_Help string
  358.        pointer.     The startup code will also work correctly from
  359.        Workbench, of course, in    this case the GADS() parser will
  360.        not be used.
  361.  
  362.         Using the GADS() parser from C does    change the way most
  363.        C programmers expect their arguments, since they    are
  364.        preparsed (note:    this does not apply unless you have changed
  365.        the default template string.)  If you are using your own
  366.        template    string,    you should consult the GADS manual page    for
  367.        information about how it    passes arguments to you.  Note that
  368.        the startup code    does install the program name as argv[0],
  369.        as is usual.
  370.  
  371.         If you wish    to use the standard startup code, link with
  372.        a.lib which provides the    glue routines necessary    to hook    up
  373.        with arp.library. In this case you must explicitly open the
  374.        library yourself.
  375.  
  376.         It is *not*    recommended that you call the ArpExit()
  377.        function    from C,    this could possibly bypass allocations that
  378.        your compiler library has made on your behalf, and cause
  379.        problems    with open files    or unreleased memory.
  380.  
  381.         All    the source code    to the startup code is provided, so
  382.        you can see exactly what    it does    and modify it should you
  383.        need to.
  384.  
  385.        3.1.1  Note to Manx Users  Manx users (but not Lattice) also
  386.        have the    files rstart, res.lib and the 32 bit versions of
  387.        these (rstart32 res32.lib).  These modules allow    you to take
  388.        advantage of the    resident program stuff from C.    Note that
  389.  
  390.  
  391.  
  392.                  Page 4
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.        ARP Prog    Manual       V1.1    Software (REL2)      February 22, 1988
  401.  
  402.  
  403.  
  404.        you do not have to write    re-entrant code    using these modules
  405.        for your    stuff to work as resident. If you do need to know
  406.        if you are running resident, (as    opposed    to running from
  407.        disk) you may examine the global    long __fromdisk__.  This
  408.        variable    will be    TRUE (-1) when you are diskloaded.  If it
  409.        is zero,    then you have been launched from the resident list.
  410.        The default stack for resident programs has been    set in the
  411.        rstart module to    10240.    If this    is too high or too low,
  412.        simply modify the value in arprescrt0.s and remake (there is
  413.        a comment in the    file illustrating what you need    to change).
  414.  
  415.        3.1.2  Note to Lattice Users  I am still    not happy with the
  416.        Lattice interface, the problem is that lattice does not
  417.        provide as much source as manx, so it is    difficult to
  418.        replace the exit    functions.  What has been done is to use
  419.        the OnExit() function to    perform    a CloseLibrary(ArpBase).
  420.        If you need OnExit() for    your own purposes, make    certain
  421.        that you    do a CloseLibrary(ArpBase) from    your exit routine.
  422.        Hopefully, the future will bring    more source from Lattice so
  423.        this can    be resolved.
  424.  
  425.         Also it does not appear possible from the supplied
  426.        documentation to    determine the total size of a merged data
  427.        area (data and bss) which is necessary for Resident support.
  428.        I am sure there must be a way, and as soon as I can find    out
  429.        from Lattice what it is,    I will try to supply resident
  430.        support files for lattice as well.
  431.  
  432.        3.2  Modula II support
  433.  
  434.        We have not yet received    a Modula II support package from
  435.        anyone.    No one directly    involved with ARP speaks Modula    II,
  436.        so we are dependent on contributors for support for this
  437.        language.  The MII support materials we do provide are from
  438.        the first release, and cover only the first release
  439.        functions.  These were contributed by Martin Taillefer.
  440.  
  441.  
  442.  
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.                  Page 5
  459.  
  460.  
  461.  
  462.  
  463.